﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css">
<!--
body {
	font-family: Geneva, Arial, Helvetica, sans-serif;
}
-->
</style>
</head>

<body>
<h2><a name="Moduleprefs_Ref" id="Moduleprefs_Ref"></a>ModulePrefs Elements and Attributes</h2>
              <p>The <code>&lt;ModulePrefs&gt;</code> section
                  in the XML file specifies characteristics of the gadget,
                  such as title, author, preferred sizing, and so on. For
                  example:</p>
              <pre>&lt;Module&gt;<br>  &lt;ModulePrefs title="Developer Forum" 
    title_url="http://groups.google.com/group/Google-Gadgets-API" <br>    height="200" 
    author="Jane Smith" 
    author_email="xxx@google.com"/&gt; <br>  &lt;Content ...&gt;<br>   ... content ...<br>  &lt;/Content&gt; <br>&lt;/Module&gt;</pre>

              <p>The users of your gadget cannot change these attributes. </p>
              <p><code>&lt;ModulePrefs&gt;</code> serves as a container element for all metadata, features, and processing rules.   For nested element descriptions, see their individual sections below. This section summarizes the elements and attributes in  <code>&lt;ModulePrefs&gt;</code>. In the sections below, the level of nesting is indicated by slashes. For example, <strong>/ModulePrefs/Locale</strong> describes the <code>&lt;Locale&gt;</code> element that is nested inside the <code>&lt;ModulePrefs&gt;</code> element. This might appear in a gadget specification as follows: </p>

              <pre>&lt;ModulePrefs&gt;<br>  &lt;Locale lang="en" country="us" /&gt;
  &lt;Locale lang="ja" country="jp" /&gt;
&lt;/ModulePrefs&gt; </pre>
              <h3>/ModulePrefs </h3>
              <p>The following table lists the <code>&lt;ModulePrefs&gt;</code> attributes that are supported in all containers. See your container documentation for any container-specific <code>&lt;ModulePrefs&gt;</code> attributes. </p>

              <table>
                  <tbody><tr>
                      <th>Attribute</th>
                      <th>Description</th>
                  </tr>
                  <tr>
                      <td><code>title</code> </td>

                      <td>Optional string that provides the title of the
                          gadget. This title is displayed in the gadget
                          title bar on iGoogle.
                          If this string contains <a href="basic.html#UP_MP">user
                          preference substitution variables</a> and you
                          are planning to submit your gadget to the 
                           iGoogle content directory, you should also provide
                          a <code>directory_title</code> for
                          directory display. </td>
                  </tr>
                  <tr>
                      <td><code>title_url </code></td>
                      <td>Optional string that provides a URL that the
                          gadget title links to. For example, you could
                          link the title to a webpage related to the gadget. </td>

                  </tr>
                  <tr>
                      <td><code>description </code></td>

                      <td>Optional string that describes the gadget.</td>
                  </tr>
                  <tr>
                      <td><code>author </code></td>

                      <td>Optional string that lists the author of the
                          gadget. </td>
                  </tr>
                  <tr>

                      <td><code>author_email </code></td>
                      <td>Optional string that provides the gadget author's
                          email address. You can use any email system,
                          but you should not use a personal email address
                          because of spam. One approach is to use an email
                          address of the form <strong>helensmith.feedback+coolgadget@gmail.com</strong>                          in your gadget spec.
                          <br>

                          <br>
                          Gmail drops everything after the plus sign
                              (+), so this email address is interpreted
                              as <strong>helensmith.feedback@gmail.com</strong>.
                          <br><br>

                          
                          You can create a Gmail account <a href="http://mail.google.com/mail/signup">here</a>.</td>
                  </tr>
                  <tr>

                      <td><code>screenshot </code></td>

                      <td>Optional string that gives the URL of a gadget
                          screenshot. This must be an image on a public
                          web site that is not blocked by <strong>robots.txt</strong>. PNG is the preferred format, though GIF and JPG are
                          also acceptable. Gadget screenshots should be
                          280 pixels wide. The height of the screenshot
                          should be the "natural" height of the
                          gadget when it's in use. </td>
                  </tr>
                  <tr>
                      <td><code>thumbnail</code></td>
                      <td>Optional string that gives the URL of a gadget
                          thumbnail. This must be an image on a public
                          web site that is not blocked by <strong>robots.txt</strong>. PNG is the preferred format, though GIF and JPG are
                          also acceptable. Gadget thumbnails should be
                          120x60 pixels. </td>

                  </tr>
        </tbody></table>
		
		      <h3>/ModulePrefs/Require and /ModulePrefs/Optional</h3>
		      <p>The <code>&lt;Require&gt;</code> and <code>&lt;Optional&gt;</code> elements declare  feature dependencies of the gadget. </p>
		<p>Attributes:		  </p>

		<ul>
		  <li><code>"feature"</code> -- The name of the feature. Required </li>
    </ul>
		<p>Examples: </p>
		<pre>&lt;Require feature="dynamic-height"/&gt;
&lt;Optional feature="shareable-prefs"/&gt;</pre>

		<h3>/ModulePrefs/Require/Param and /ModulePrefs/Optional/Param</h3>
		<p>These elements provide configuration parameters for a feature.   </p>
		<p>Attributes:</p>
		<ul>
          <li><code>"name"</code> -- The name of the parameter. Required.</li>
        </ul>

        <h3>ModulePrefs/Preload</h3>
        <p>The <code>&lt;Preload&gt;</code> element instructs the container to fetch data from a remote source during the gadget   rendering process. This data is inlined in the rendered output, and   it is available immediately when gadget code is executed. Use of this method should   reduce latency for gadgets that depend on content from remote servers to   render. </p>
		<p>Attributes: </p>
		<ul>
          <li><code>"href"</code> -- A URL specifiying the location of the data to prefetch. Required. </li>

		  <li><code>"authz"</code> -- The authentication type to use for making this request. Valid values are <code>"none"</code> (default), <code>"signed"</code>, and <code>"oauth"</code>. Optional. </li>
    </ul>
		<h3>ModulePrefs/Icon</h3>

		<p>The <code>&lt;Icon&gt;</code> element specifies a 16px x 16px image that containers can associate with a particular gadget (for example, the container might display the icon  next to the gadget's name in the left nav bar). </p>
		<p>  The content of the <code>&lt;Icon&gt;</code> tag can be one of the following: </p>
		<ul>
		  <li>An HTTP URL pointing to an image file on the web </li>

		  <li>Inlined base64-encoded image data. </li>
    </ul>
		<p>Attributes:</p>
		<ul>
          <li><code>"mode"</code> -- The encoding used for the icon when embedding an image.   Currently, only base64 is supported. Optional. </li>
          <li><code>"type"</code> -- The MIME of the embedded icon text. Optional. </li>

    </ul>
		<p>Examples:</p>
		<pre>&lt;ModulePrefs title="My gadget"&gt;
  &lt;Icon&gt;http://remote/favicon.ico&lt;/Icon&gt;
&lt;/ModulePrefs&gt;

&lt;ModulePrefs title="My gadget"&gt;

  &lt;Icon mode="base64" type="image/png"&gt;<em>base64 encoded data</em>&lt;/Icon&gt;
&lt;/ModulePrefs&gt;</pre>
		<h3 id="L10N_Ref">ModulePrefs/Locale</h3>
		<p>The <code>&lt;Locale&gt;</code> element specifies the locales supported by your gadget. You can
                  also use it to specify message bundles, as described
                  in <a href="i18n.html">Gadgets and Internationalization</a>.</p>

		<p>Attributes:</p>
		<ul>
		  <li><code>"lang"</code> -- The language associated with the locale. Optional.</li>
		  <li><code>"country"</code> -- The country associated with the locale. Optional.</li>
		  <li><code>"messages"</code> -- A URL that points to a message bundle. Message bundles are XML files that contain the translated strings for a given locale. For more information, see <a href="i18n.html">Gadgets and Internationalization</a>. Optional.	      </li>

          <li><code>"language_direction"</code> -- The direction of the gadget. Optional. Its value can either be "rtl" (right-to-left) or "ltr" (left-to-right). The default is "ltr". This attribute lets you create gadgets that support both left-to-right and right-to-left languages. For more discussion of this topic, see <a href="i18n.html#BIDI">Creating Bi-directional Gadgets</a>. You can use the following substitution variables in conjunction with language_direction: 
            <ul>
              <li><code>__BIDI_START_EDGE__</code>: The value is "left" when the gadget is in LTR-mode and "right" when the gadget is in RTL-mode. </li>
            
            <li><code>__BIDI_END_EDGE__</code>: The value is "right" when the gadget is in LTR-mode and "left" when the gadget is in RTL-mode.</li>
            <li><code>__BIDI_DIR__</code>: The value of this variable is "ltr" when the gadget is in LTR-mode and "rtl" when the gadget is in RTL-mode.</li>

            <li><code>__BIDI_REVERSE_DIR__</code>: The value of this variable is "rtl" when the gadget is in LTR-mode and "ltr" when the gadget is in RTL-mode. </li>
          </ul>
	</li></ul>
		<p>For example, this snippet specifies two different locales: </p>

              <pre>&lt;ModulePrefs&gt;
  &lt;Locale lang="en" country="us" /&gt;

  &lt;Locale lang="ja" country="jp" /&gt;
&lt;/ModulePrefs&gt;</pre>
              <p>The "lang" (language) and "country" attributes
                  are both optional, but you must have at least one of
                  them for each <code>&lt;Locale&gt;</code>.
                  If you omit either attribute, the value is equivalent
                  to "*" and "ALL". If you specify
                  a country and no language, it is assumed that your gadget
                  supports all languages associated with the country. Likewise,
                  if you specify a language and no country, it is assumed
                  that your gadget supports all countries associated with
                  the language. </p>

              <p>The valid values for language are ISO639-1 two-digit language codes, and   for country they are ISO 3166-1 alpha-2 codes.</p>
              <p>There are a few exceptions to the usual language rules:</p>

              <ul>
                  <li>Simplified Chinese:<code> lang="zh-cn"</code> (typically
                      for country="cn").</li>

                  <li>Traditional Chinese: <code>lang="zh-tw"</code> (typically
                      for country="tw" or "hk", Taiwan
                      or Hong Kong, respectively). </li>
              </ul>

              <h3>ModulePrefs/Link</h3>
              <p>A container-specific link. For example, this tag could be used to support new link types, such as <span id="eh740">gadgetsHelp</span> and <span id="eh741">gadgetsSupport</span>. </p>
        <p>Attributes:</p>
        <ul>
          <li><code>"rel"</code> -- A value that triggers a lifecycle event
            . Required. </li>

		  <li><span id="zo:v3"><code>"href"</code> -- A URL. Required. </span></li>
		  <li><span id="zo:v4"><code>"method"</code> -- The method (POST or GET) by which the request should be send. The default is GET. Optional. </span></li>
    </ul>
		<p>A container can optionally support sending lifecycle events to an 
		  application developer's site by sending relevant query-params to a URL 
		  endpoint.  To receive these events you can use the <code>&lt;Link&gt;</code> tag..  Each <code>&lt;Link&gt;</code> tag has a <code>rel</code> and an <code>href</code> attribute.  The 
		  <code>href</code> attribute denotes the endpont where event pings are sent.  If the 
		  <code>rel</code> attribute is <code>"opensocialevent"</code> then all events are sent to that endpoint. 
		  If the <code>rel</code> attribute matches <code>"opensocialevent.TYPE",</code> then events of <code>TYPE</code> are sent 
		  to that endpoint.  An optional method attribute can be set to POST or 
		  GET to specify how the request should be sent.  The default is GET. 
		  Here are some examples:		</p>

		<pre>&lt;link rel="event" href="http://www.example.com/pingme" method="POST/&gt;
&lt;link rel="event.addapp" href="http://www.example.com/add" /&gt;
&lt;link rel="event.removeapp" href="http://www.example.com/remove" /&gt;</pre>
		<p>Most events  have information about one or more opensocial ID 
		  values.  These ID values are passed as one or more ID attributes. 
		  Note that a single ping can aggregate a number of events by specifying 
		  many ID values.    </p>
		<p>The following event types are defined:</p>
		<ul>
		  <li><code>addapp</code>    -- Users that have installed the app (ID). 
		    Optional "from" designates how the user added this 
		    app.  Possible values are <code>"invite"</code>,  <code>"gallery"</code>, and <code>"external"</code>.</li>

		  <li><code>removeapp</code> -- IDs of users that have removed the app </li>
		  <li><code>app</code>       -- <code>action={enabled|disabled|approved} 
		    reason={policy|quota|maintenance}</code></li>
		  <li><code>invite</code>    -- <code>id</code> is people invited, 
		    <code>from_id</code> is the ID that sent the invitation. </li>
</body>
</html>
